Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/scope/001-025/scopedisk8/debug/debug.docs

Text File | 1995-03-18 | 11KB | 314 lines

                    -- Amiga Debugger --

Software and documentation by Jim Thibodeau and Larry LaPlume.

Amiga Debugger is the official resident debugger here at SLADE Software.

This is the first release of this utility. We here at SLADE welcome
opinions, suggestions and bug reports. The only way we can fix it is
if we know there is something wrong!

We can be reached at Acorn BBS [phone] (c/o Larry LaPlume).
Or you can write to us:

    Jim Thibodeau                Larry Laplume
    40 Ryefield Dr.                P.O. box 5291 Station A
    Old Orchard Beach, ME. 04064        Portland, ME 04101


                    --  Debug Commands --

Command line syntax:
   Is geared toward the heavy duty hacker.   Generally, a command
line consists of a single letter command,  an optional space, and
1 or two arguments.  Arguments may be numeric as with Disassemble
and Memory dump or string as with  Load file.  Some commands take
no arguments,  such  as  eXit  and  display  Segment  list.   The
Disassemble and  Memory  dump  commands  take  arguments  only in
Hexidecimal form, or  from  the  contents  of  any  of the 8 Data
registers, the  8  Address  registers,  or  the  Program  Counter
register.   When  specifying  the  contents  of  a  register, the
desired register MUST be enclosed in parenthesis.

   Note that Debug shares  its  very  own  Task Control Structure
with the program being  debugged.   Things that the program being
debugged does to  its Task  Control  Structure,  it automatically
does to Debug's Task Control  Structure.   For example, a program
being debugged, that calls the dos.library  Exit() function, will
also cause the debugger to Exit().

   When  Disassembling  or  dumping  memory,  none,  one  or  two
arguments may be given.  If no  argument  is given, the operation
will begin where the last operation left off.  If one argument is
given, the operation  will  begin  at  the address specified, and
continue for a few  lines.   If  two  arguments  are  given,  the
operation will begin with  the  address  specified  by  the first
argument, and continue to the  second  argument.  The disassemble
and memory dump routines both support the ^c user break keystroke
to stop them from continuing to their normal completion.

   When the debugger is ready to accept  commands it will display
a minus sign as a  prompt.   Commands  may  then  be typed at the
keyboard, followed  by  the  return  or  enter  keys on the Amiga
keyboard.  A space after the  single  letter  prompt is optional,
but a space before the  single  letter  command  will confuse the
debugger. Thus:

-d 100 200
-d100 200
-d         100         200

All do the same thing, while:

-  d 100 200

Will not work at all.

Here is a list of  supported  commands  that  may be typed at the
prompt:

Command: D   (Disassemble memory)
Examples:
-d 100 200   Will disassemble memory from address $100 to $200

-d (a0)      Disassemble  memory  pointed  to by the contents of
         register A0.

-d  (pc)     Disassemble  memory  at  the  value of the Program
         Counter.

-d (a0,d0)   Disassemble memory at the value of the register A0
         plus the contents of the  D0  register.  This  is
         similar to the processor's  d(An,Xi)  mode  except
         for  the  lack of index size specifier - the  size
         always  being  long,  and  the lack of any dis-
         placement value.

Command: M   (Memory dump)
Example:
-m 100 200   Display memory contents from address $100 to $200

-m (sp)      Display  memory  contents  pointed  to  by the stack
         pointer.

Command: X   (eXit the debugger)
Example:
-x           Quit debug utility.


Command: S   (Show Segment list of loaded file)
Example:
-s           Display segment list of last file loaded.

Command: L   (Load a file for debugging)
Example:
-l [[path/]Filespec]  Will read a file from disk into memory.

Command:  R  (Display MC68000 Register/Flag values)
Example:
-r           Display the contents of important MC68000 registers.

 Using the r command at the  prompt  with  no parameters displays
the contents of the Amiga's MC68000's registers and flags.


Command: R   (Modify MC68000 Register/Flag values)
Examples:
-r a0 100    Load register A0 with the value $100.

-r d0 +100   Loads register D0 with the decimal value +100.

-r d0 -1     Loads register d0 with the decimal value of -1.

-r sr %101   Loads the  Status  Register  with  the  binary value
         %101.

-r z 1       Forces the Zero flag on.

 All registers and flags that  are  displayed with the -r command
may be modified with  the  -r  command  as  well.  Just  type the
Motorola standard Symbol name of the register or flag followed by
the  desired  value.   Note  that  Flags  may  be  either  0 or 1
corresponding to off and on, clear or set.

Values entered may be preceeded by a "+" sign to denote a decimal
number, a "-" sign to denote  a  negative  decimal  number, a "%"
sign to permit entry of a binary number,  or a "$" sign to denote
a hexidecimal number. If no  leading  sign is entered the default
is hexidecimal.
Use care when directly  modifying  the program counter and status
registers.

Command: C   (Set Command Line Tail)
Example:
-c Desired Command line tail

      Declare "Desired Command line tail" as a command tail.  The
Debugger will set up the string in  memory, and install a pointer
to it and the length of the specified  string in the MC68000s' A0
and D0 registers  each  time,  BUT  NOT  UNTIL  the registers are
initialized. (See the "I" command)

Command: I    (Initialize MC68000 Registers)
Example:
-i            Initialize ALL MC68000 register values.

   When  initializing,  Command  line  tail  values  (if any) are
installed in registers  A0  and  D0.   Also  initialized  are the
Program  Counter,  and  User   Stack   Pointer  registers.   When
initializing the USP, the top of stack is found, then the address
of a termination routine is pushed onto the stack, so the program
can run to   its  completion,  and  remain  in  the  Debugger for
further examination.

                    * * * N O T E * * *

    The  following  conditions  AUTOMATICALLY   perform  the  "I"
command:
1. Normal termination of the  program.  (registers  are displayed
before reset).
2. Attempting to Load a file. (even if the load fails).

Command: G     (Go execute instructions)
Examples:
-g 100         Begin executing instructions at address $100

-g             Begin executing instructions at the address of the
           Program Counter.  To  view  the  program  counter,
           use  the  "R" command.

The Go command supports break  points.   These may be inserted in
the code by the programmer by  the  use  of the MC68000's ILLEGAL
instruction, a TRAP, or  the  line  1010  & 1111 emulators.  Zero
divide conditions, as well as  Privilege  violation,  and Address
errors work  like  breakpoints.    Note  the  trap  number in the
register frame to determine the cause of the break.

It is also important to note that  some types of errors including
zero divide, TRAP #x, and  address  errors may alter the value of
the program counter displayed  in  the  register frame.  In other
words, it may be necessary  to  scan  back  a few bytes or words,
with the disassembler to view the offensive instruction.



Command: T     (Execute in Trace mode)
Example:
-t             Trace  the  instruction  at  the  Current Program
           Counter.

Trace works just like  Go,  except  that  only ONE instruction is
executed, and a register frame is displayed AFTER the instruction
executes.  Additionally, the  debugger  will disassemble the next
instruction to be  executed.  A  trap  number  of  9 will usually
appear when tracing.

Note that due  to  characteristics  of  the  Amiga's multitasking
system, attempting to trace  certain  types  of processor errors,
including zero divide condition, can, and probably will crash the
entire system.


Command: Z      (Zip through a subroutine)
Example:
-z  Zip through instruction at the current Program Counter.

Zip is usefull when tracing  code.   When the next instruction to
be executed is a BSR or a JSR and  tracing through the subroutine
is not desirable, just press  "z".   The debugger will attempt to
execute the subroutine, and  stop  at the instruction immediately
following it.

Command: N      (Display next instruction)
Example:
-n              Disassemble   the  instruction  at  the  current
        Program Counter.

The N command displays  the  instruction  that  the  MC68000 will
attempt to Execute is the "G"  or  "T" or "Z" commands are issued
with no paramaters. Note that "N"  also updates debugger internal
variables so that "M" and "D"  defaults  are reset to the current
Program Counter.


            * * * * * *  Break Points * * * * *

 Debug supports limited,  multiple  break  points.  Up to 8 break
points may be active at once. Use the -p command to view, set, or
clear any or  all  break  points.  When  setting  a  break point,
the debugger stores the requested address of a break point, stores
the  contents  of  that  address,  and  replaces  it  with  a the
MC68000's  ILLEGAL opcode.  Clearing the break point replaces the
ILLEGAL instruction with  the  saved  contents.   When  the Amiga
attempts to execute the  installed  ILLEGAL  instruction, via the
'g' or 'z' commands the debugger considers that a break point and
displays the appropriate information.

Command:  P     Display all active break Points.
Examples:
-p              Lists all currently set break points.

-p 1            List  the  current  status  of break point number
        one.

Command:  PS    break Point Set.
Example:
-ps 1 100       Sets Break point number one to address $100.

Command:  PC    break Point Clear.
Example:
-pc 1           Removes  break  point  one,  and  restores saved
        contents of that address.

Command:  PX    Remove ALL break points.
Example:
-px             Remove any of  the  eight  break points that are
            set.

Command:  W     Toggle private window on/off.
Example:
-w              Close private window  if it's open, Open private
        window if it's closed.


Debug.doc Page 6


Note that this window is only for  Debug's input and output - any
program being debugged will have  its  own I/O streams. (Normally
the CLI window).


          - - - Number format conversions - - -

Command: $   (Display the value of hexidecimal input number)
Example:
-$ 400       Display the Decimal and Binary equates of $400

Command: %   (Display the value of binary input number
Example:
-% 1101101   Display  the  Decimal  and  Hexidecimal  equates of
         %1101101

Command: +   (Display the value of decimal input number)
Example:
-+1024       Display the Hexidecimal  and Binary equates of +1024
         Negative decimal  numbers  may  also  be  converted
         using  the + command.  Note that if  the  number  to
          be converted is negative the + command must be used,
         followed by "-" and the number.
Example:
-+-1024      Display the Hexadecimal and Binary equates of -1024

Command: A   (Convert the specified APTR to a BPTR)
Example:
-a 4         Will convert the number $4 to a BPTR and display the
         value of the computed BPTR.

Command: B   (Convert the specified BPTR to an APTR)
Example:
-b 1         Will convert the BPTR  $1 to an APTR and display the
         value of the computed APTR.